Skip to main content

Agents

  • optional

A Template Package can include agents to be created or updated in the AI service for the selected project during deployment. Each agent is listed in the manifest.agents array. The manifest entry names the JSON definition file under agents/; the file holds the agent configuration (and may duplicate or override fields also set in the manifest).

Agent definition files must be placed inside the agents folder in the ZIP archive. The file value should match the file path relative to agents/ in the ZIP.

For each entry, the manifest row is merged with the JSON file as { ...fileAgent, ...agentDef }, so manifest values override the file when both define the same property.

Each definition file must contain a single JSON object (not an array). After merging, the agent must include:

  • name — display name (maps to _name)
  • background — system / instruction text (maps to _background)
  • userType — stable key for the agent (maps to _userType)
  • config — a JSON object (not an array) with:
    • model — model identifier (maps to _config._model)
    • provider — provider identifier (maps to _config._provider)

Optional fields:

  • tools — array of tool name strings (maps to _tools when non-empty)
  • agentClass — non-empty string when present (maps to _agentClass)
  • knowledgebases — array of strings; each string must be a knowledge base name (the same value as _name in the AI service), not userType. These names must match knowledge bases that exist when the agent step runs—typically from manifest.files[].knowledgebase.name entries deployed in the same package, or already present in the project.

ifExists#

If an agent with the same name or userType already exists:

  • default (or omitted/empty): keep the existing agent unchanged and skip this manifest entry.
  • update — the existing agent is updated with the merged definition (including tools, optional agentClass, and resolved knowledge bases).
  • recreate — the existing agent is deleted, then created again from the definition.

Values are compared case-insensitively.

Any value other than default, update, or recreate fails validation.

Deploy behavior#

  • File uploads and file-linked knowledge bases run before agents.
  • A package can include files (with optional knowledgebase) and agents together in one deploy.
  • agents[].knowledgebases must list knowledge base name values that exist when the agent step runs (including ones created earlier in the same deployment).
  • If an agent references a knowledge base expected from manifest.files[].knowledgebase, that knowledge base must have been created successfully earlier in the same deploy. This requires the file row to resolve correctly via _path + _name to a real file under fileUploads/; otherwise, the knowledge base is skipped and the agent reference fails.
  • If ifExists has an invalid value, the entry fails validation.

Complete example#

// manifest.json{   "Template Name": "Success KB Agent Team",   "Template Version": "1.0.0",   "files": [      {         "_name": "property-mapping.md",         "_path": "",         "_tags": [],         "knowledgebase": {            "name": "property-mapping-md",            "userType": "property_mapping_md",            "ifExists": "default"         }      },      {         "_name": "agent-bg-source.txt",         "_path": "",         "_tags": [],         "knowledgebase": {            "name": "agent-bg-md",            "userType": "agent_bg_md",            "ifExists": "recreate"         }      }   ],   "agents": [      {         "name": "My Test Agent 1",         "userType": "test_agent_1",         "file": "test-agent-1.json"      },      {         "name": "My Test Agent 2",         "userType": "test_agent_2",         "file": "test-agent-2.json",         "ifExists": "update"      }   ]}
// Package ZIP layoutSuccess KB Agent Team.zip /|-- fileUploads /|   |-- property-mapping.md|   |-- agent-bg-source.txt|-- agents /|   |-- test-agent-1.json|   |-- test-agent-2.json|-- manifest.json
// agents/test-agent-1.json{   "background": "You are responsible for finding the collection and item that matches the users request.",   "tools": ["GetNamedUserItemsTool", "GetRelatedItemsTool"],   "knowledgebases": ["property-mapping-md"],   "config": {      "model": "gpt-4o",      "provider": "openai"   }}

Field split: name and userType for each agent are often supplied in the manifest; background, tools, knowledgebases, and config can live in the JSON file (or in the manifest if you prefer overrides). The knowledgebases array uses the string property-mapping-md because that is the knowledge base name from the file entry's knowledgebase block, not property_mapping_md (userType).